Product
Introducing License Enforcement in Socket
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
mdast-util-mdx-expression
Advanced tools
mdast extension to parse and serialize MDX (or MDX.js) expressions
The `mdast-util-mdx-expression` package is a utility for working with MDX (Markdown with JSX) expressions within the MDAST (Markdown Abstract Syntax Tree) format. It provides tools to parse, transform, and stringify MDX expressions embedded in Markdown documents.
Parsing MDX Expressions
This feature allows you to parse MDX expressions from a Markdown string into an MDAST tree. The code sample demonstrates how to parse a simple MDX expression.
const { fromMarkdown } = require('mdast-util-mdx-expression');
const mdxExpression = 'const x = 42;';
const tree = fromMarkdown(mdxExpression);
console.log(tree);
Stringifying MDX Expressions
This feature allows you to convert an MDAST tree containing MDX expressions back into a Markdown string. The code sample demonstrates how to stringify a simple MDX expression.
const { toMarkdown } = require('mdast-util-mdx-expression');
const tree = {
type: 'mdxFlowExpression',
value: 'const x = 42;'
};
const markdown = toMarkdown(tree);
console.log(markdown);
Transforming MDAST Trees
This feature allows you to traverse and transform MDAST trees containing MDX expressions. The code sample demonstrates how to visit and modify an MDX expression within an MDAST tree.
const { visit } = require('unist-util-visit');
const { fromMarkdown, toMarkdown } = require('mdast-util-mdx-expression');
const mdxExpression = 'const x = 42;';
const tree = fromMarkdown(mdxExpression);
visit(tree, 'mdxFlowExpression', node => {
node.value = 'const y = 24;';
});
const newMarkdown = toMarkdown(tree);
console.log(newMarkdown);
The `remark-mdx` package is a plugin for the `remark` ecosystem that enables parsing and transforming MDX content. It provides similar functionality to `mdast-util-mdx-expression` but is more integrated into the `remark` processing pipeline.
mdast extensions to parse and serialize MDX expressions ({Math.PI}
).
This package contains two extensions that add support for MDX expression syntax
in markdown to mdast.
These extensions plug into
mdast-util-from-markdown
(to support parsing
expressions in markdown into a syntax tree) and
mdast-util-to-markdown
(to support serializing
expressions in syntax trees to markdown).
You can use these extensions when you are working with
mdast-util-from-markdown
and mdast-util-to-markdown
already.
When working with mdast-util-from-markdown
, you must combine this package
with micromark-extension-mdx-expression
.
When you are working with syntax trees and want all of MDX, use
mdast-util-mdx
instead.
All these packages are used in remark-mdx
, which
focusses on making it easier to transform content by abstracting these
internals away.
This package is ESM only. In Node.js (version 14.14+ and 16.0+), install with npm:
npm install mdast-util-mdx-expression
In Deno with esm.sh
:
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@1'
In browsers with esm.sh
:
<script type="module">
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'https://esm.sh/mdast-util-mdx-expression@1?bundle'
</script>
Say our document example.mdx
contains:
{
a + 1
}
b {true}.
…and our module example.js
looks as follows:
import fs from 'node:fs/promises'
import * as acorn from 'acorn'
import {fromMarkdown} from 'mdast-util-from-markdown'
import {toMarkdown} from 'mdast-util-to-markdown'
import {mdxExpression} from 'micromark-extension-mdx-expression'
import {mdxExpressionFromMarkdown, mdxExpressionToMarkdown} from 'mdast-util-mdx-expression'
const doc = await fs.readFile('example.mdx')
const tree = fromMarkdown(doc, {
extensions: [mdxExpression({acorn, addResult: true})],
mdastExtensions: [mdxExpressionFromMarkdown]
})
console.log(tree)
const out = toMarkdown(tree, {extensions: [mdxExpressionToMarkdown]})
console.log(out)
…now running node example.js
yields (positional info removed for brevity):
{
type: 'root',
children: [
{
type: 'mdxFlowExpression',
value: '\na + 1\n',
data: {
estree: {
type: 'Program',
body: [
{
type: 'ExpressionStatement',
expression: {
type: 'BinaryExpression',
left: {type: 'Identifier', name: 'a'},
operator: '+',
right: {type: 'Literal', value: 1, raw: '1'}
}
}
],
sourceType: 'module'
}
}
},
{
type: 'paragraph',
children: [
{type: 'text', value: 'b '},
{
type: 'mdxTextExpression',
value: 'true',
data: {
estree: {
type: 'Program',
body: [
{
type: 'ExpressionStatement',
expression: {type: 'Literal', value: true, raw: 'true'}
}
],
sourceType: 'module'
}
}
},
{type: 'text', value: '.'}
]
}
]
}
{
a + 1
}
b {true}.
This package exports the identifiers
mdxExpressionFromMarkdown
and
mdxExpressionToMarkdown
.
There is no default export.
mdxExpressionFromMarkdown
Extension for mdast-util-from-markdown
to enable
MDX expressions.
When using the micromark syntax extension with addResult
, nodes
will have a data.estree
field set to an ESTree Program
node.
mdxExpressionToMarkdown
Extension for mdast-util-to-markdown
to enable MDX
expressions.
MdxFlowExpression
MDX expression node, occurring in flow (block) (TypeScript type).
import type {Program} from 'estree-jsx'
import type {Literal} from 'mdast'
interface MdxFlowExpression extends Literal {
type: 'mdxFlowExpression'
data?: {estree?: Program | null | undefined} & Literal['data']
}
MdxTextExpression
MDX expression node, occurring in text (block) (TypeScript type).
import type {Program} from 'estree-jsx'
import type {Literal} from 'mdast'
interface MdxTextExpression extends Literal {
type: 'mdxTextExpression'
data?: {estree?: Program | null | undefined} & Literal['data']
}
MdxFlowExpressionHast
Same as MdxFlowExpression
, but registered with
@types/hast
(TypeScript type).
import type {Program} from 'estree-jsx'
import type {Literal} from 'hast'
interface MdxFlowExpressionHast extends Literal {
type: 'mdxFlowExpression'
data?: {estree?: Program | null | undefined} & Literal['data']
}
MdxTextExpressionHast
Same as MdxTextExpression
, but registered with
@types/hast
(TypeScript type).
import type {Program} from 'estree-jsx'
import type {Literal} from 'hast'
interface MdxTextExpressionHast extends Literal {
type: 'mdxTextExpression'
data?: {estree?: Program | null | undefined} & Literal['data']
}
MDX expressions have no representation in HTML.
Though, when you are dealing with MDX, you will likely go through hast.
You can enable passing MDX expressions through to hast by configuring
mdast-util-to-hast
with
passThrough: ['mdxFlowExpression', 'mdxTextExpression']
.
See Syntax in micromark-extension-mdx-expression
.
The following interfaces are added to mdast by this utility.
MdxFlowExpression
interface MdxFlowExpression <: Literal {
type: "mdxFlowExpression"
}
MdxFlowExpression (Literal) represents a JavaScript
expression embedded in flow (block).
It can be used where flow content is expected.
Its content is represented by its value
field.
For example, the following markdown:
{
1 + 1
}
Yields:
{type: 'mdxFlowExpression', value: '\n1 + 1\n'}
MdxTextExpression
interface MdxTextExpression <: Literal {
type: "mdxTextExpression"
}
MdxTextExpression (Literal) represents a JavaScript
expression embedded in text (span, inline).
It can be used where phrasing content is expected.
Its content is represented by its value
field.
For example, the following markdown:
a {1 + 1} b.
Yields:
{type: 'mdxTextExpression', value: '1 + 1'}
FlowContent
(MDX expression)type FlowContentMdxExpression = MdxFlowExpression | FlowContent
PhrasingContent
(MDX expression)type PhrasingContentMdxExpression = MdxTextExpression | PhrasingContent
This package is fully typed with TypeScript.
It exports the additional types MdxFlowExpression
,
MdxFlowExpressionHast
,
MdxTextExpression
, and
MdxTextExpressionHast
.
It also registers the node types with @types/mdast
and @types/hast
.
If you’re working with the syntax tree, make sure to import this utility
somewhere in your types, as that registers the new node types in the tree.
/**
* @typedef {import('mdast-util-mdx-expression')}
*/
import {visit} from 'unist-util-visit'
/** @type {import('mdast').Root} */
const tree = getMdastNodeSomeHow()
visit(tree, (node) => {
// `node` can now be an expression node.
})
Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 14.14+ and 16.0+. Our projects sometimes work with older versions, but this is not guaranteed.
This plugin works with mdast-util-from-markdown
version 1+ and
mdast-util-to-markdown
version 1+.
remarkjs/remark-mdx
— remark plugin to support MDXsyntax-tree/mdast-util-mdx
— mdast utility to support MDXmicromark/micromark-extension-mdx-expression
— micromark extension to parse MDX expressionsSee contributing.md
in syntax-tree/.github
for
ways to get started.
See support.md
for ways to get help.
This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.
FAQs
mdast extension to parse and serialize MDX (or MDX.js) expressions
The npm package mdast-util-mdx-expression receives a total of 2,279,192 weekly downloads. As such, mdast-util-mdx-expression popularity was classified as popular.
We found that mdast-util-mdx-expression demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Ensure open-source compliance with Socket’s License Enforcement Beta. Set up your License Policy and secure your software!
Product
We're launching a new set of license analysis and compliance features for analyzing, managing, and complying with licenses across a range of supported languages and ecosystems.
Product
We're excited to introduce Socket Optimize, a powerful CLI command to secure open source dependencies with tested, optimized package overrides.